'.\" t
.TH "clbuild" "1M" "Jun 20, 2006" "1\&.2\&.0"
.SH NAME
clbuild \- Build Cluster Topology configuration 

.SH SYNOPSIS
.TS
l l.
clbuild [\fB--keeplogs\fP]	Build/Reconfigure Cluster Topology

clbuild \fB-?\fP	Show brief usage information
.TE

.SH DESCRIPTION
This utility is used initially to define the cluster configuration. The
main purpose of the routine is to ensure that the environment appears
to be able to support the clustering software correctly. 

As with the \fIclbuildapp(1M)\fP command it is run initially when the
cluster topology is defined, and must be used after any changes to the 
cluster configuration - whether the cluster is currently running or not.

This commands checks the environment and compares it to the contents
of the \fIclconf.xml(5)\fP file on the local host. Thus changes to the
cluster configuration can only take place if both machines can be contacted
via the 'ssh' protocol using their respective hostnames.

Before the \fIclbuild(1M)\fP utility is run the administrator should ensure the
following are true:

.TP 4
[1]
The \fIclconf.xml(5)\fP file exists and accurately reflects the cluster 
topolofy and parameters that wish to be used. 
.TP
[2]
IP communication is available between the nodes using the networks specified
in the 'networks' section of the configuration file. If the servers in question are
running firewall software [such as IP Tables] it is recommended that they are 
configurated to allow all communication between all interfaces on the two
machines.
.TP
[3]
That 'ssh' is available in the current PATH and that root equivalence
is available using 'ssh' between both nodes (via the hostnames) in
both directions - without requiring a password or pass-phrase to
be entered.
.TP
[4]
Ensure that the kernel is making use of LVM v1 or LVM v2 (device mapper).
.TP
[5]
Ensure that the required command set for the necessary version of LVM are
available.
.RE

If you have not completed any of these steps, or not completed them correctly
the utility will provide a suitable error before exiting.

.SH CONFIGURATION CHANGES
If all checks are completed successfully then the script will perform the
following changes (if required):

.TP 4
[1]
Ensure that the cluster configuration file is copied to the remote node,
creating the required directory structure if necessary.
.TP
[2]
Create directory structures for log files both locally and remotely.
.TP
[3]
Generate device for the DRBD devices if they do not exist. It should be
noted that this software does not work with the 'devfs' file system at
present, though support for the newer "udev" is built-in.
.TP
[4] Resource files will be created to record which resources are owned by
applications used in the cluster. 

.SH ARGUMENTS
Linuxha.net always attempts to make the life of the administrator as 
straightforward as possible; and this is reflected in the list of
arguments supported by \fIclbuild(1M)\fP... there is only one!
though future versions are likely to increase these enhance these.

.TP 8
.B --keeplogs
The tool keeps detailed logging information of each operation that is
performed though only a summary appears on screen. Usually when a section
of work has completed successfully the log in question is removed - and is
only kept when a fatal error occurs.

When this argument is specified the logs will be kept - even if no errors
occur.

HERE
.SH REBUILDING THE CLUSTER TOPOLOGY
If the cluster configuration already exists, the running the command
again is supported. As with application rebuilds, this process can be done 
on-line or off-line.

The changes are considered off-line if the cluster daemon is not running 
locally, otherwise the change is on-line. If an on-line change is being
performed the '--force' flag is required.

When an on-line change is performed the process will communicate with 
all running cluster daemons and indicate to them that they should re-read
there relevant configurations as appropriate.

Of course not all attributes can be taken dynamically, though the network
topology is (so able to add and remove cards from existing networks, or
even add and remove networks), locking timeouts are, and many of the
attributes used by the main cluster daemons are, including:

.TS
l l.
\fBkeepalive\fP	- time between check of other cluster daemon
\fBwarn\fP	- time after which to show warning of impending failure.
\fBdead\fP	- time after which to treat node as dead if no contact.
.TE

.SH EXIT STATUS
The \fIclbuild(1M)\fP utility makes use of many error codes, but in summary
it will return a non-zero number for an error or zero if the configuration
has been processed successfully.

If an error is generated many of the more obscure error conditions provide
several lines of information to help ensure the administrator is able to
resolve such problems as quickly as possible.

.SH FILES
The configuration of the cluster makes little use of log files - it sends any
messages to standard output if the '-v' flag is specified. However, it does
generate 'resource flag files' which are important and these should not be
deleted.

.TP 20
/etc/cluster/clconf.xml
This file is expected to contain the details of the cluster topology on the
local machine. A copy of this file will be sent to the node in the cluster
once it has successfully been configured.
.TP
/etc/cluster/.resources/ports
The directory is created and contains details of which network ports are in
used or are available. As with all resource files the user should not 
alter any ofthese files manually. When the cluster is originally built all entries
in this directory will have the following format:

NNNN.free
.TP
/etc/cluster/.resources/drbd
This directory contains files which are used to handle DRBD device allocation
to each of the file systems managed in the cluster. When the cluster is
initially built all files in this directory will appear with the following
format:

NN.free

.SH SEE ALSO
.TS
l l.
clbuildapp(1M)	- Build / Synchronise cluster application 
clstat(1M)	- Show cluster status information
cldeamon(1M)	- Cluster status Daemon
clstartapp(1M)	- Start a clustered application
clhaltapp(1M)	- Halt a clustered application
clconf.xml(5)	- Overall cluster topology configuration file
appconf.xml(5)	- Configuration of an application used by the cluster
.TE

.SH NOTES

.SH AUTHOR
The \fIclbuild(1M)\fP utility was written by Simon Edwards, 2003-2005. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha website - please see
http://linuxha.net/index.pl?ARGS=findproject:linuxha for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

